.TH std::saturate_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::saturate_cast \- std::saturate_cast

.SH Synopsis
   Defined in header <numeric>
   template< class T, class U >                (since C++26)
   constexpr T saturate_cast( U x ) noexcept;

   Converts the value x to a value of type T, clamping x between the minimum and
   maximum values of type T.

   It is a compile-time error if either T or U is not a signed or unsigned integer type
   (including standard integer type and extended integer type).

.SH Parameters

   x - an integer value

.SH Return value

     * x, if x is representable as a value of type T. Otherwise,
     * either the largest or smallest representable value of type T, whichever is
       closer to the value of x.

.SH Exceptions

   Throws no exceptions.

.SH Notes

         Feature-test macro         Value    Std          Feature
   __cpp_lib_saturation_arithmetic 202311L (C++26) Saturation arithmetic

.SH Possible implementation

   See libstdc++ (gcc).

.SH Example

   Can be previewed on Compiler Explorer.


// Run this code

 #include <cstdint>
 #include <limits>
 #include <numeric>

 int main()
 {
     constexpr std::int16_t x1{696};

     constexpr std::int8_t x2 = std::saturate_cast<std::int8_t>(x1);
     static_assert(x2 == std::numeric_limits<std::int8_t>::max());

     constexpr std::uint8_t x3 = std::saturate_cast<std::uint8_t>(x1);
     static_assert(x3 == std::numeric_limits<std::uint8_t>::max());

     constexpr std::int16_t y1{-696};

     constexpr std::int8_t y2 = std::saturate_cast<std::int8_t>(y1);
     static_assert(y2 == std::numeric_limits<std::int8_t>::min());

     constexpr std::uint8_t y3 = std::saturate_cast<std::uint8_t>(y1);
     static_assert(y3 == 0);
 }

.SH See also

   bit_cast reinterpret the object representation of one type as that of another
   (C++20)  \fI(function template)\fP
   clamp    clamps a value between a pair of boundary values
   \fI(C++17)\fP  \fI(function template)\fP
   in_range checks if an integer value is in the range of a given integer type
   (C++20)  \fI(function template)\fP
